home *** CD-ROM | disk | FTP | other *** search
/ Personal Computer World 2009 February / PCWFEB09.iso / Software / Linux / SLAX 6.0.8 / slax-6.0.8.iso / slax / base / 006-devel.lzm / usr / include / sasl / saslplug.h < prev    next >
Encoding:
C/C++ Source or Header  |  2006-05-27  |  32.1 KB  |  954 lines
  1. /* saslplug.h --  API for SASL plug-ins
  2.  */
  3.  
  4. #ifndef SASLPLUG_H
  5. #define SASLPLUG_H 1
  6.  
  7. #ifndef MD5GLOBAL_H
  8. #include "md5global.h"
  9. #endif
  10. #ifndef MD5_H
  11. #include "md5.h"
  12. #endif
  13. #ifndef HMAC_MD5_H
  14. #include "hmac-md5.h"
  15. #endif
  16. #ifndef PROP_H
  17. #include "prop.h"
  18. #endif
  19.  
  20. #ifdef __cplusplus
  21. extern "C" {
  22. #endif
  23.  
  24. /* callback to lookup a sasl_callback_t for a connection
  25.  * input:
  26.  *  conn        -- the connection to lookup a callback for
  27.  *  callbacknum -- the number of the callback
  28.  * output:
  29.  *  pproc       -- pointer to the callback function (set to NULL on failure)
  30.  *  pcontext    -- pointer to the callback context (set to NULL on failure)
  31.  * returns:
  32.  *  SASL_OK -- no error
  33.  *  SASL_FAIL -- unable to find a callback of the requested type
  34.  *  SASL_INTERACT -- caller must use interaction to get data
  35.  */
  36. typedef int sasl_getcallback_t(sasl_conn_t *conn,
  37.                    unsigned long callbackid,
  38.                    int (**pproc)(),
  39.                    void **pcontext);
  40.  
  41. /* The sasl_utils structure will remain backwards compatible unless
  42.  * the SASL_*_PLUG_VERSION is changed incompatibly
  43.  * higher SASL_UTILS_VERSION numbers indicate more functions are available
  44.  */
  45. #define SASL_UTILS_VERSION 4
  46.  
  47. /* utility function set for plug-ins
  48.  */
  49. typedef struct sasl_utils {
  50.     int version;
  51.  
  52.     /* contexts */
  53.     sasl_conn_t *conn;
  54.     sasl_rand_t *rpool;
  55.     void *getopt_context;
  56.  
  57.     /* option function */
  58.     sasl_getopt_t *getopt;
  59.     
  60.     /* allocation functions: */
  61.     sasl_malloc_t *malloc;
  62.     sasl_calloc_t *calloc;
  63.     sasl_realloc_t *realloc;
  64.     sasl_free_t *free;
  65.  
  66.     /* mutex functions: */
  67.     sasl_mutex_alloc_t *mutex_alloc;
  68.     sasl_mutex_lock_t *mutex_lock;
  69.     sasl_mutex_unlock_t *mutex_unlock;
  70.     sasl_mutex_free_t *mutex_free;
  71.  
  72.     /* MD5 hash and HMAC functions */
  73.     void (*MD5Init)(MD5_CTX *);
  74.     void (*MD5Update)(MD5_CTX *, const unsigned char *text, unsigned int len);
  75.     void (*MD5Final)(unsigned char [16], MD5_CTX *);
  76.     void (*hmac_md5)(const unsigned char *text, int text_len,
  77.              const unsigned char *key, int key_len,
  78.              unsigned char [16]);
  79.     void (*hmac_md5_init)(HMAC_MD5_CTX *, const unsigned char *key, int len);
  80.     /* hmac_md5_update() is just a call to MD5Update on inner context */
  81.     void (*hmac_md5_final)(unsigned char [16], HMAC_MD5_CTX *);
  82.     void (*hmac_md5_precalc)(HMAC_MD5_STATE *,
  83.                  const unsigned char *key, int len);
  84.     void (*hmac_md5_import)(HMAC_MD5_CTX *, HMAC_MD5_STATE *);
  85.  
  86.     /* mechanism utility functions (same as above): */
  87.     int (*mkchal)(sasl_conn_t *conn, char *buf, unsigned maxlen,
  88.           unsigned hostflag);
  89.     int (*utf8verify)(const char *str, unsigned len);
  90.     void (*rand)(sasl_rand_t *rpool, char *buf, unsigned len);
  91.     void (*churn)(sasl_rand_t *rpool, const char *data, unsigned len);
  92.  
  93.     /* This allows recursive calls to the sasl_checkpass() routine from
  94.      * within a SASL plug-in.  This MUST NOT be used in the PLAIN mechanism
  95.      * as sasl_checkpass MAY be a front-end for the PLAIN mechanism.
  96.      * This is intended for use by the non-standard LOGIN mechanism and
  97.      * potentially by a future mechanism which uses public-key technology to
  98.      * set up a lightweight encryption layer just for sending a password.
  99.      */
  100.     int (*checkpass)(sasl_conn_t *conn,
  101.              const char *user, unsigned userlen,
  102.              const char *pass, unsigned passlen);
  103.     
  104.     /* Access to base64 encode/decode routines */
  105.     int (*decode64)(const char *in, unsigned inlen,
  106.             char *out, unsigned outmax, unsigned *outlen);
  107.     int (*encode64)(const char *in, unsigned inlen,
  108.             char *out, unsigned outmax, unsigned *outlen);
  109.  
  110.     /* erase a buffer */
  111.     void (*erasebuffer)(char *buf, unsigned len);
  112.  
  113.     /* callback to sasl_getprop() and sasl_setprop() */
  114.     int (*getprop)(sasl_conn_t *conn, int propnum, const void **pvalue);
  115.     int (*setprop)(sasl_conn_t *conn, int propnum, const void *value);
  116.  
  117.     /* callback function */
  118.     sasl_getcallback_t *getcallback;
  119.  
  120.     /* format a message and then pass it to the SASL_CB_LOG callback
  121.      *
  122.      * use syslog()-style formatting (printf with %m as a human readable text
  123.      * (strerror()) for the error specified as the parameter).
  124.      * The implementation may use a fixed size buffer not smaller
  125.      * than 512 octets if it securely truncates the message.
  126.      *
  127.      * level is a SASL_LOG_* level (see sasl.h)
  128.      */
  129.     void (*log)(sasl_conn_t *conn, int level, const char *fmt, ...);
  130.  
  131.     /* callback to sasl_seterror() */
  132.     void (*seterror)(sasl_conn_t *conn, unsigned flags, const char *fmt, ...);
  133.  
  134.     /* spare function pointer */
  135.     int *(*spare_fptr)();
  136.  
  137.     /* auxiliary property utilities */
  138.     struct propctx *(*prop_new)(unsigned estimate);
  139.     int (*prop_dup)(struct propctx *src_ctx, struct propctx **dst_ctx);
  140.     int (*prop_request)(struct propctx *ctx, const char **names);
  141.     const struct propval *(*prop_get)(struct propctx *ctx);
  142.     int (*prop_getnames)(struct propctx *ctx, const char **names,
  143.              struct propval *vals);
  144.     void (*prop_clear)(struct propctx *ctx, int requests);
  145.     void (*prop_dispose)(struct propctx **ctx);
  146.     int (*prop_format)(struct propctx *ctx, const char *sep, int seplen,
  147.                char *outbuf, unsigned outmax, unsigned *outlen);
  148.     int (*prop_set)(struct propctx *ctx, const char *name,
  149.             const char *value, int vallen);
  150.     int (*prop_setvals)(struct propctx *ctx, const char *name,
  151.             const char **values);
  152.     void (*prop_erase)(struct propctx *ctx, const char *name);
  153.     int (*auxprop_store)(sasl_conn_t *conn,
  154.              struct propctx *ctx, const char *user);
  155.  
  156.     /* for additions which don't require a version upgrade; set to 0 */
  157.     int (*spare_fptr1)();
  158.     int (*spare_fptr2)();
  159. } sasl_utils_t;
  160.  
  161. /*
  162.  * output parameters from SASL API
  163.  *
  164.  * created / destroyed by the glue code, though probably filled in
  165.  * by a combination of the plugin, the glue code, and the canon_user callback.
  166.  *
  167.  */
  168. typedef struct sasl_out_params {
  169.     unsigned doneflag;        /* exchange complete */
  170.  
  171.     const char *user;        /* canonicalized user name */
  172.     const char *authid;        /* canonicalized authentication id */
  173.  
  174.     unsigned ulen;        /* length of canonicalized user name */
  175.     unsigned alen;        /* length of canonicalized authid */
  176.  
  177.     /* security layer information */
  178.     unsigned maxoutbuf;         /* Maximum buffer size, which will
  179.                                    produce buffer no bigger than the
  180.                                    negotiated SASL maximum buffer size */
  181.     sasl_ssf_t mech_ssf;   /* Should be set non-zero if negotiation of a
  182.                  * security layer was *attempted*, even if
  183.                 * the negotiation failed */
  184.     void *encode_context;
  185.     int (*encode)(void *context, const struct iovec *invec, unsigned numiov,
  186.           const char **output, unsigned *outputlen);
  187.     void *decode_context;
  188.     int (*decode)(void *context, const char *input, unsigned inputlen,
  189.           const char **output, unsigned *outputlen);
  190.     
  191.     /* Pointer to delegated (client's) credentials, if supported by
  192.        the SASL mechanism */
  193.     void *client_creds;
  194.  
  195.     /* for additions which don't require a version upgrade; set to 0 */
  196.     void *spare_ptr2;
  197.     void *spare_ptr3;
  198.     void *spare_ptr4;
  199.     int (*spare_fptr1)();
  200.     int (*spare_fptr2)();
  201.     int spare_int1;
  202.     int spare_int2;
  203.     int spare_int3;
  204.     int spare_int4;
  205.  
  206.     /* set to 0 initially, this allows a plugin with extended parameters
  207.      * to work with an older framework by updating version as parameters
  208.      * are added.
  209.      */
  210.     int param_version;
  211. } sasl_out_params_t;
  212.  
  213.  
  214.  
  215. /* Used by both client and server side plugins */
  216. typedef enum  {
  217.     SASL_INFO_LIST_START = 0,
  218.     SASL_INFO_LIST_MECH,
  219.     SASL_INFO_LIST_END
  220. } sasl_info_callback_stage_t;
  221.  
  222.  
  223.  
  224. /******************************
  225.  * Client Mechanism Functions *
  226.  ******************************/
  227.  
  228. /*
  229.  * input parameters to client SASL plugin
  230.  *
  231.  * created / destroyed by the glue code
  232.  *
  233.  */
  234. typedef struct sasl_client_params {
  235.     const char *service;    /* service name */
  236.     const char *serverFQDN;    /* server fully qualified domain name */
  237.     const char *clientFQDN;    /* client's fully qualified domain name */
  238.     const sasl_utils_t *utils;    /* SASL API utility routines --
  239.                  * for a particular sasl_conn_t,
  240.                  * MUST remain valid until mech_free is
  241.                  * called */
  242.     const sasl_callback_t *prompt_supp; /* client callback list */
  243.     const char *iplocalport;    /* server IP domain literal & port */
  244.     const char *ipremoteport;    /* client IP domain literal & port */
  245.  
  246.     unsigned servicelen;    /* length of service */
  247.     unsigned slen;        /* length of serverFQDN */
  248.     unsigned clen;        /* length of clientFQDN */
  249.     unsigned iploclen;        /* length of iplocalport */
  250.     unsigned ipremlen;        /* length of ipremoteport */
  251.  
  252.     /* application's security requirements & info */
  253.     sasl_security_properties_t props;
  254.     sasl_ssf_t external_ssf;    /* external SSF active */
  255.  
  256.     /* for additions which don't require a version upgrade; set to 0 */
  257.     void *spare_ptr1;
  258.     void *spare_ptr2;
  259.     void *spare_ptr3;
  260.     void *spare_ptr4;
  261.  
  262.     /* Canonicalize a user name from on-wire to internal format
  263.      *  added rjs3 2001-05-23
  264.      *  Must be called once user name aquired if canon_user is non-NULL.
  265.      *  conn        connection context
  266.      *  in          user name from wire protocol (need not be NUL terminated)
  267.      *  len         length of user name from wire protocol (0 = strlen(user))
  268.      *  flags       for SASL_CU_* flags
  269.      *  oparams     the user, authid, ulen, alen, fields are
  270.      *              set appropriately after canonicalization/copying and
  271.      *              authorization of arguments
  272.      *
  273.      *  responsible for setting user, ulen, authid, and alen in the oparams
  274.      *  structure
  275.      *
  276.      *  default behavior is to strip leading and trailing whitespace, as
  277.      *  well as allocating space for and copying the parameters.
  278.      *
  279.      * results:
  280.      *  SASL_OK       -- success
  281.      *  SASL_NOMEM    -- out of memory
  282.      *  SASL_BADPARAM -- invalid conn
  283.      *  SASL_BADPROT  -- invalid user/authid
  284.      */
  285.     int (*canon_user)(sasl_conn_t *conn,
  286.                     const char *in, unsigned len,
  287.                     unsigned flags,
  288.                     sasl_out_params_t *oparams);
  289.  
  290.     int (*spare_fptr1)();
  291.  
  292.     int spare_int1;
  293.     int spare_int2;
  294.     int spare_int3;
  295.  
  296.     /* flags field as passed to sasl_client_new */
  297.     unsigned flags;
  298.  
  299.     /* set to 0 initially, this allows a plugin with extended parameters
  300.      * to work with an older framework by updating version as parameters
  301.      * are added.
  302.      */
  303.     int param_version;
  304. } sasl_client_params_t;
  305.  
  306. /* features shared between client and server */
  307. /* These allow the glue code to handle client-first and server-last issues */
  308.  
  309. /* This indicates that the mechanism prefers to do client-send-first
  310.  * if the protocol allows it. */
  311. #define SASL_FEAT_WANT_CLIENT_FIRST 0x0002
  312.  
  313. /* This feature is deprecated, instead, plugins should set *serverout to
  314.  * non-NULL and return SASL_OK intelligently to allow flexible use of
  315.  * server-last semantics */
  316. /* #define SASL_FEAT_WANT_SERVER_LAST 0x0004 */
  317.  
  318. /* This feature is deprecated, instead plugins should correctly set
  319.  * SASL_FEAT_SERVER_FIRST as needed */
  320. /* #define SASL_FEAT_INTERNAL_CLIENT_FIRST 0x0008 */
  321.  
  322. /* This indicates that the plugin is server-first only. 
  323.  * Not defining either of SASL_FEAT_SERVER_FIRST or 
  324.  * SASL_FEAT_WANT_CLIENT_FIRST indicates that the mechanism will take care 
  325.  * of the client-first situation internally.
  326.  */
  327. #define SASL_FEAT_SERVER_FIRST 0x0010
  328.  
  329. /* This plugin allows proxying */
  330. #define SASL_FEAT_ALLOWS_PROXY 0x0020
  331.  
  332. /* client plug-in features */
  333. #define SASL_FEAT_NEEDSERVERFQDN 0x0001
  334.  
  335. /* a C object for a client mechanism
  336.  */
  337. typedef struct sasl_client_plug {
  338.     /* mechanism name */
  339.     const char *mech_name;
  340.  
  341.     /* best mech additional security layer strength factor */
  342.     sasl_ssf_t max_ssf;
  343.  
  344.     /* best security flags, as defined in sasl_security_properties_t */
  345.     unsigned security_flags;
  346.  
  347.     /* features of plugin */
  348.     unsigned features;
  349.  
  350.     /* required prompt ids, NULL = user/pass only */
  351.     const unsigned long *required_prompts;
  352.     
  353.     /* global state for mechanism */
  354.     void *glob_context;
  355.     
  356.     /* create context for mechanism, using params supplied
  357.      *  glob_context   -- from above
  358.      *  params         -- params from sasl_client_new
  359.      *  conn_context   -- context for one connection
  360.      * returns:
  361.      *  SASL_OK        -- success
  362.      *  SASL_NOMEM     -- not enough memory
  363.      *  SASL_WRONGMECH -- mech doesn't support security params
  364.      */
  365.     int (*mech_new)(void *glob_context,
  366.             sasl_client_params_t *cparams,
  367.             void **conn_context);
  368.     
  369.     /* perform one step of exchange.  NULL is passed for serverin on
  370.      * first step.
  371.      * returns:
  372.      *  SASL_OK        -- success
  373.      *  SASL_INTERACT  -- user interaction needed to fill in prompts
  374.      *  SASL_BADPROT   -- server protocol incorrect/cancelled
  375.      *  SASL_BADSERV   -- server failed mutual auth
  376.      */
  377.     int (*mech_step)(void *conn_context,
  378.              sasl_client_params_t *cparams,
  379.              const char *serverin,
  380.              unsigned serverinlen,
  381.              sasl_interact_t **prompt_need,
  382.              const char **clientout,
  383.              unsigned *clientoutlen,
  384.              sasl_out_params_t *oparams);
  385.     
  386.     /* dispose of connection context from mech_new
  387.      */
  388.     void (*mech_dispose)(void *conn_context, const sasl_utils_t *utils);
  389.     
  390.     /* free all global space used by mechanism
  391.      *  mech_dispose must be called on all mechanisms first
  392.      */
  393.     void (*mech_free)(void *glob_context, const sasl_utils_t *utils);
  394.      
  395.     /* perform precalculations during a network round-trip
  396.      *  or idle period.  conn_context may be NULL
  397.      *  returns 1 if action taken, 0 if no action taken
  398.      */
  399.     int (*idle)(void *glob_context,
  400.         void *conn_context,
  401.         sasl_client_params_t *cparams);
  402.  
  403.     /* for additions which don't require a version upgrade; set to 0 */
  404.     int (*spare_fptr1)();
  405.     int (*spare_fptr2)();
  406. } sasl_client_plug_t;
  407.  
  408. #define SASL_CLIENT_PLUG_VERSION         4
  409.  
  410. /* plug-in entry point:
  411.  *  utils       -- utility callback functions
  412.  *  max_version -- highest client plug version supported
  413.  * returns:
  414.  *  out_version -- client plug version of result
  415.  *  pluglist    -- list of mechanism plug-ins
  416.  *  plugcount   -- number of mechanism plug-ins
  417.  * results:
  418.  *  SASL_OK       -- success
  419.  *  SASL_NOMEM    -- failure
  420.  *  SASL_BADVERS  -- max_version too small
  421.  *  SASL_BADPARAM -- bad config string
  422.  *  ...
  423.  */
  424. typedef int sasl_client_plug_init_t(const sasl_utils_t *utils,
  425.                     int max_version,
  426.                     int *out_version,
  427.                     sasl_client_plug_t **pluglist,
  428.                     int *plugcount);
  429.  
  430.  
  431. /* add a client plug-in
  432.  */
  433. LIBSASL_API int sasl_client_add_plugin(const char *plugname,
  434.                        sasl_client_plug_init_t *cplugfunc);
  435.  
  436. typedef struct client_sasl_mechanism
  437. {
  438.     int version;
  439.  
  440.     char *plugname;
  441.     const sasl_client_plug_t *plug;
  442. } client_sasl_mechanism_t;
  443.  
  444. typedef void sasl_client_info_callback_t (client_sasl_mechanism_t *m,
  445.                       sasl_info_callback_stage_t stage,
  446.                       void *rock);
  447.  
  448. /* Dump information about available client plugins */
  449. LIBSASL_API int sasl_client_plugin_info (const char *mech_list,
  450.     sasl_client_info_callback_t *info_cb,
  451.     void *info_cb_rock);
  452.  
  453.  
  454. /********************
  455.  * Server Functions *
  456.  ********************/
  457.  
  458. /* log message formatting routine */
  459. typedef void sasl_logmsg_p(sasl_conn_t *conn, const char *fmt, ...);
  460.  
  461. /*
  462.  * input parameters to server SASL plugin
  463.  *
  464.  * created / destroyed by the glue code
  465.  *
  466.  */
  467. typedef struct sasl_server_params {
  468.     const char *service;    /* NULL = default service for user_exists
  469.                    and setpass */
  470.     const char *appname;    /* name of calling application */
  471.     const char *serverFQDN;    /* server default fully qualified domain name
  472.                  * (e.g., gethostname) */
  473.     const char *user_realm;    /* realm for user (NULL = client supplied) */
  474.     const char *iplocalport;    /* server IP domain literal & port */
  475.     const char *ipremoteport;    /* client IP domain literal & port */
  476.  
  477.     unsigned servicelen;    /* length of service */
  478.     unsigned applen;        /* length of appname */
  479.     unsigned slen;        /* length of serverFQDN */
  480.     unsigned urlen;        /* length of user_realm */
  481.     unsigned iploclen;        /* length of iplocalport */
  482.     unsigned ipremlen;        /* length of ipremoteport */
  483.  
  484.     /* This indicates the level of logging desired.  See SASL_LOG_*
  485.      * in sasl.h
  486.      *
  487.      * Plug-ins can ignore this and just pass their desired level to
  488.      * the log callback.  This is primarily used to eliminate logging which
  489.      * might be a performance problem (e.g., full protocol trace) and
  490.      * to select between SASL_LOG_TRACE and SASL_LOG_PASS alternatives
  491.      */
  492.     int log_level;
  493.  
  494.     const sasl_utils_t *utils;    /* SASL API utility routines --
  495.                  * for a particular sasl_conn_t,
  496.                  * MUST remain valid until mech_free is
  497.                  * called */
  498.     const sasl_callback_t *callbacks;    /* Callbacks from application */
  499.  
  500.     /* application's security requirements */
  501.     sasl_security_properties_t props;
  502.     sasl_ssf_t external_ssf;    /* external SSF active */
  503.  
  504.     /* Pointer to the function which takes the plaintext passphrase and
  505.      *  transitions a user to non-plaintext mechanisms via setpass calls.
  506.      *  (NULL = auto transition not enabled/supported)
  507.      *
  508.      *  If passlen is 0, it defaults to strlen(pass).
  509.      *  returns 0 if no entry added, 1 if entry added
  510.      */
  511.     int (*transition)(sasl_conn_t *conn, const char *pass, unsigned passlen);
  512.  
  513.     /* Canonicalize a user name from on-wire to internal format
  514.      *  added cjn 1999-09-21
  515.      *  Must be called once user name acquired if canon_user is non-NULL.
  516.      *  conn        connection context
  517.      *  user        user name from wire protocol (need not be NUL terminated)
  518.      *  ulen        length of user name from wire protocol (0 = strlen(user))
  519.      *  flags       for SASL_CU_* flags
  520.      *  oparams     the user, authid, ulen, alen, fields are
  521.      *              set appropriately after canonicalization/copying and
  522.      *              authorization of arguments
  523.      *
  524.      *  responsible for setting user, ulen, authid, and alen in the oparams
  525.      *  structure
  526.      *
  527.      *  default behavior is to strip leading and trailing whitespace, as
  528.      *  well as allocating space for and copying the parameters.
  529.      *
  530.      * results:
  531.      *  SASL_OK       -- success
  532.      *  SASL_NOMEM    -- out of memory
  533.      *  SASL_BADPARAM -- invalid conn
  534.      *  SASL_BADPROT  -- invalid user/authid
  535.      */
  536.     int (*canon_user)(sasl_conn_t *conn,
  537.               const char *user, unsigned ulen,
  538.               unsigned flags,
  539.               sasl_out_params_t *oparams);
  540.     
  541.     /* auxiliary property context (see definitions in prop.h)
  542.      *  added cjn 2000-01-30
  543.      *
  544.      * NOTE: these properties are the ones associated with the
  545.      * canonicalized "user" (user to login as / authorization id), not
  546.      * the "authid" (user whose credentials are used / authentication id)
  547.      * Prefix the property name with a "*" if a property associated with
  548.      * the "authid" is interesting.
  549.      */
  550.     struct propctx *propctx;
  551.  
  552.     /* for additions which don't require a version upgrade; set to 0 */
  553.     void *spare_ptr1;
  554.     void *spare_ptr2;
  555.     void *spare_ptr3;
  556.     void *spare_ptr4;
  557.     int (*spare_fptr1)();
  558.     int (*spare_fptr2)();
  559.     int spare_int1;
  560.     int spare_int2;
  561.     int spare_int3;
  562.  
  563.     /* flags field as passed to sasl_server_new */
  564.     unsigned flags;
  565.  
  566.     /* set to 0 initially, this allows a plugin with extended parameters
  567.      * to work with an older framework by updating version as parameters
  568.      * are added.
  569.      */
  570.     int param_version;
  571. } sasl_server_params_t;
  572.  
  573. /* logging levels (more levels may be added later, if necessary):
  574.  */
  575. #define SASL_LOG_NONE  0    /* don't log anything */
  576. #define SASL_LOG_ERR   1    /* log unusual errors (default) */
  577. #define SASL_LOG_FAIL  2    /* log all authentication failures */
  578. #define SASL_LOG_WARN  3    /* log non-fatal warnings */
  579. #define SASL_LOG_NOTE  4    /* more verbose than LOG_WARN */
  580. #define SASL_LOG_DEBUG 5    /* more verbose than LOG_NOTE */
  581. #define SASL_LOG_TRACE 6    /* traces of internal protocols */
  582. #define SASL_LOG_PASS  7    /* traces of internal protocols, including
  583.                  * passwords */
  584.  
  585. /* additional flags for setpass() function below:
  586.  */
  587. /*      SASL_SET_CREATE                     create user if pass non-NULL */
  588. /*      SASL_SET_DISABLE                    disable user */
  589. #define SASL_SET_REMOVE  SASL_SET_CREATE /* remove user if pass is NULL */
  590.  
  591. /* features for server plug-in
  592.  */
  593. #define SASL_FEAT_SERVICE    0x0200 /* service-specific passwords supported */
  594. #define SASL_FEAT_GETSECRET  0x0400 /* sasl_server_{get,put}secret_t callbacks
  595.                      * required by plug-in */
  596.  
  597. /* a C object for a server mechanism
  598.  */
  599. typedef struct sasl_server_plug {
  600.     /* mechanism name */
  601.     const char *mech_name;
  602.  
  603.     /* best mech additional security layer strength factor */
  604.     sasl_ssf_t max_ssf;
  605.  
  606.     /* best security flags, as defined in sasl_security_properties_t */
  607.     unsigned security_flags;
  608.  
  609.     /* features of plugin */
  610.     unsigned features;
  611.     
  612.     /* global state for mechanism */
  613.     void *glob_context;
  614.  
  615.     /* create a new mechanism handler
  616.      *  glob_context  -- global context
  617.      *  sparams       -- server config params
  618.      *  challenge     -- server challenge from previous instance or NULL
  619.      *  challen       -- length of challenge from previous instance or 0
  620.      * out:
  621.      *  conn_context  -- connection context
  622.      *  errinfo       -- error information
  623.      *
  624.      * returns:
  625.      *  SASL_OK       -- successfully created mech instance
  626.      *  SASL_*        -- any other server error code
  627.      */
  628.     int (*mech_new)(void *glob_context,
  629.             sasl_server_params_t *sparams,
  630.             const char *challenge,
  631.             unsigned challen,
  632.             void **conn_context);
  633.     
  634.     /* perform one step in exchange
  635.      *
  636.      * returns:
  637.      *  SASL_OK       -- success, all done
  638.      *  SASL_CONTINUE -- success, one more round trip
  639.      *  SASL_*        -- any other server error code
  640.      */
  641.     int (*mech_step)(void *conn_context,
  642.              sasl_server_params_t *sparams,
  643.              const char *clientin,
  644.              unsigned clientinlen,
  645.              const char **serverout,
  646.              unsigned *serveroutlen,
  647.              sasl_out_params_t *oparams);
  648.     
  649.     /* dispose of a connection state
  650.      */
  651.     void (*mech_dispose)(void *conn_context, const sasl_utils_t *utils);
  652.     
  653.     /* free global state for mechanism
  654.      *  mech_dispose must be called on all mechanisms first
  655.      */
  656.     void (*mech_free)(void *glob_context, const sasl_utils_t *utils);
  657.     
  658.     /* set a password (optional)
  659.      *  glob_context  -- global context
  660.      *  sparams       -- service, middleware utilities, etc. props ignored
  661.      *  user          -- user name
  662.      *  pass          -- password/passphrase (NULL = disable/remove/delete)
  663.      *  passlen       -- length of password/passphrase
  664.      *  oldpass       -- old password/passphrase (NULL = transition)
  665.      *  oldpasslen    -- length of password/passphrase
  666.      *  flags         -- see above
  667.      *
  668.      * returns:
  669.      *  SASL_NOCHANGE -- no change was needed
  670.      *  SASL_NOUSER   -- no entry for user
  671.      *  SASL_NOVERIFY -- no mechanism compatible entry for user
  672.      *  SASL_PWLOCK   -- password locked
  673.      *  SASL_DIABLED  -- account disabled
  674.      *  etc.
  675.      */
  676.     int (*setpass)(void *glob_context,
  677.            sasl_server_params_t *sparams,
  678.            const char *user,
  679.            const char *pass, unsigned passlen,
  680.            const char *oldpass, unsigned oldpasslen,
  681.            unsigned flags);
  682.  
  683.     /* query which mechanisms are available for user
  684.      *  glob_context  -- context
  685.      *  sparams       -- service, middleware utilities, etc. props ignored
  686.      *  user          -- NUL terminated user name
  687.      *  maxmech       -- max number of strings in mechlist (0 = no output)
  688.      * output:
  689.      *  mechlist      -- an array of C string pointers, filled in with
  690.      *                   mechanism names available to the user
  691.      *
  692.      * returns:
  693.      *  SASL_OK       -- success
  694.      *  SASL_NOMEM    -- not enough memory
  695.      *  SASL_FAIL     -- lower level failure
  696.      *  SASL_DISABLED -- account disabled
  697.      *  SASL_NOUSER   -- user not found
  698.      *  SASL_BUFOVER  -- maxmech is too small
  699.      *  SASL_NOVERIFY -- user found, but no mechanisms available
  700.      */
  701.     int (*user_query)(void *glob_context,
  702.               sasl_server_params_t *sparams,
  703.               const char *user,
  704.               int maxmech,
  705.               const char **mechlist);
  706.      
  707.     /* perform precalculations during a network round-trip
  708.      *  or idle period.  conn_context may be NULL (optional)
  709.      *  returns 1 if action taken, 0 if no action taken
  710.      */
  711.     int (*idle)(void *glob_context,
  712.         void *conn_context,
  713.         sasl_server_params_t *sparams);
  714.  
  715.     /* check if mechanism is available
  716.      *  optional--if NULL, mechanism is available based on ENABLE= in config
  717.      *
  718.      *  If this routine sets conn_context to a non-NULL value, then the call
  719.      *  to mech_new will be skipped.  This should not be done unless
  720.      *  there's a significant performance benefit, since it can cause
  721.      *  additional memory allocation in SASL core code to keep track of
  722.      *  contexts potentially for multiple mechanisms.
  723.      *
  724.      *  This is called by the first call to sasl_listmech() for a
  725.      *  given connection context, thus for a given protocol it may
  726.      *  never be called.  Note that if mech_avail returns SASL_NOMECH,
  727.      *  then that mechanism is considered disabled for the remainder
  728.      *  of the session.  If mech_avail returns SASL_NOTDONE, then a
  729.      *  future call to mech_avail may still return either SASL_OK
  730.      *  or SASL_NOMECH.
  731.      *
  732.      *  returns SASL_OK on success,
  733.      *          SASL_NOTDONE if mech is not available now, but may be later
  734.      *                       (e.g. EXTERNAL w/o auth_id)
  735.      *          SASL_NOMECH if mech disabled
  736.      */
  737.     int (*mech_avail)(void *glob_context,
  738.               sasl_server_params_t *sparams,
  739.               void **conn_context);
  740.  
  741.     /* for additions which don't require a version upgrade; set to 0 */
  742.     int (*spare_fptr2)();
  743. } sasl_server_plug_t;
  744.  
  745. #define SASL_SERVER_PLUG_VERSION 4
  746.  
  747. /* plug-in entry point:
  748.  *  utils         -- utility callback functions
  749.  *  plugname      -- name of plug-in (may be NULL)
  750.  *  max_version   -- highest server plug version supported
  751.  * returns:
  752.  *  out_version   -- server plug-in version of result
  753.  *  pluglist      -- list of mechanism plug-ins
  754.  *  plugcount     -- number of mechanism plug-ins
  755.  * results:
  756.  *  SASL_OK       -- success
  757.  *  SASL_NOMEM    -- failure
  758.  *  SASL_BADVERS  -- max_version too small
  759.  *  SASL_BADPARAM -- bad config string
  760.  *  ...
  761.  */
  762. typedef int sasl_server_plug_init_t(const sasl_utils_t *utils,
  763.                     int max_version,
  764.                     int *out_version,
  765.                     sasl_server_plug_t **pluglist,
  766.                     int *plugcount);
  767.  
  768. /* 
  769.  * add a server plug-in
  770.  */
  771. LIBSASL_API int sasl_server_add_plugin(const char *plugname,
  772.                        sasl_server_plug_init_t *splugfunc);
  773.  
  774.  
  775. typedef struct server_sasl_mechanism
  776. {
  777.     int version;
  778.     int condition; /* set to SASL_NOUSER if no available users;
  779.               set to SASL_CONTINUE if delayed plugin loading */
  780.     char *plugname; /* for AUTHSOURCE tracking */
  781.     const sasl_server_plug_t *plug;
  782.     char *f;       /* where should i load the mechanism from? */
  783. } server_sasl_mechanism_t;
  784.  
  785. typedef void sasl_server_info_callback_t (server_sasl_mechanism_t *m,
  786.                       sasl_info_callback_stage_t stage,
  787.                       void *rock);
  788.  
  789.  
  790. /* Dump information about available server plugins (separate functions are
  791.    used for canon and auxprop plugins) */
  792. LIBSASL_API int sasl_server_plugin_info (const char *mech_list,
  793.     sasl_server_info_callback_t *info_cb,
  794.     void *info_cb_rock);
  795.  
  796.  
  797. /*********************************************************
  798.  * user canonicalization plug-in -- added cjn 1999-09-29 *
  799.  *********************************************************/
  800.  
  801. typedef struct sasl_canonuser {
  802.     /* optional features of plugin (set to 0) */
  803.     int features;
  804.  
  805.     /* spare integer (set to 0) */
  806.     int spare_int1;
  807.  
  808.     /* global state for plugin */
  809.     void *glob_context;
  810.  
  811.     /* name of plugin */
  812.     char *name;
  813.  
  814.     /* free global state for plugin */
  815.     void (*canon_user_free)(void *glob_context, const sasl_utils_t *utils);
  816.  
  817.     /* canonicalize a username
  818.      *  glob_context     -- global context from this structure
  819.      *  sparams          -- server params, note user_realm&propctx elements
  820.      *  user             -- user to login as (may not be NUL terminated)
  821.      *  len              -- length of user name (0 = strlen(user))
  822.      *  flags            -- for SASL_CU_* flags
  823.      *  out              -- buffer to copy user name
  824.      *  out_max          -- max length of user name
  825.      *  out_len          -- set to length of user name
  826.      *
  827.      *  note that the output buffers MAY be the same as the input buffers.
  828.      *
  829.      * returns
  830.      *  SASL_OK         on success
  831.      *  SASL_BADPROT    username contains invalid character
  832.      */
  833.     int (*canon_user_server)(void *glob_context,
  834.                  sasl_server_params_t *sparams,
  835.                  const char *user, unsigned len,
  836.                  unsigned flags,
  837.                  char *out,
  838.                  unsigned out_umax, unsigned *out_ulen);
  839.  
  840.     int (*canon_user_client)(void *glob_context,
  841.                  sasl_client_params_t *cparams,
  842.                  const char *user, unsigned len,
  843.                  unsigned flags,
  844.                  char *out,
  845.                  unsigned out_max, unsigned *out_len);
  846.  
  847.     /* for additions which don't require a version upgrade; set to 0 */
  848.     int (*spare_fptr1)();
  849.     int (*spare_fptr2)();
  850.     int (*spare_fptr3)();
  851. } sasl_canonuser_plug_t;
  852.  
  853. #define SASL_CANONUSER_PLUG_VERSION 5
  854.  
  855. /* default name for canonuser plug-in entry point is "sasl_canonuser_init"
  856.  *  similar to sasl_server_plug_init model, except only returns one
  857.  *  sasl_canonuser_plug_t structure;
  858.  */
  859. typedef int sasl_canonuser_init_t(const sasl_utils_t *utils,
  860.                   int max_version,
  861.                   int *out_version,
  862.                   sasl_canonuser_plug_t **plug,
  863.                   const char *plugname);
  864.  
  865. /* add a canonuser plugin
  866.  */
  867. LIBSASL_API int sasl_canonuser_add_plugin(const char *plugname,
  868.                   sasl_canonuser_init_t *canonuserfunc);
  869.  
  870. /******************************************************
  871.  * auxiliary property plug-in -- added cjn 1999-09-29 *
  872.  ******************************************************/
  873.  
  874. typedef struct sasl_auxprop_plug {
  875.     /* optional features of plugin (none defined yet, set to 0) */
  876.     int features;
  877.  
  878.     /* spare integer, must be set to 0 */
  879.     int spare_int1;
  880.  
  881.     /* global state for plugin */
  882.     void *glob_context;
  883.  
  884.     /* free global state for plugin (OPTIONAL) */
  885.     void (*auxprop_free)(void *glob_context, const sasl_utils_t *utils);
  886.  
  887.     /* fill in fields of an auxiliary property context
  888.      *  last element in array has id of SASL_AUX_END
  889.      *  elements with non-0 len should be ignored.
  890.      */
  891.     void (*auxprop_lookup)(void *glob_context,
  892.                sasl_server_params_t *sparams,
  893.                unsigned flags,
  894.                const char *user, unsigned ulen);
  895.  
  896.     /* name of the auxprop plugin */
  897.     char *name;
  898.  
  899.     /* store the fields/values of an auxiliary property context (OPTIONAL)
  900.      *
  901.      * if ctx is NULL, just check if storing properties is enabled
  902.      *
  903.      * returns
  904.      *  SASL_OK         on success
  905.      *  SASL_FAIL       on failure
  906.      */
  907.     int (*auxprop_store)(void *glob_context,
  908.              sasl_server_params_t *sparams,
  909.              struct propctx *ctx,
  910.              const char *user, unsigned ulen);
  911. } sasl_auxprop_plug_t;
  912.  
  913. /* auxprop lookup flags */
  914. #define SASL_AUXPROP_OVERRIDE 0x01 /* if clear, ignore auxiliary properties
  915.                     * with non-zero len field.  If set,
  916.                     * override value of those properties */
  917. #define SASL_AUXPROP_AUTHZID  0x02 /* if clear, we are looking up the
  918.                     * authid flags (prefixed with *), otherwise
  919.                     * we are looking up the authzid flags
  920.                     * (no prefix) */
  921.  
  922. #define SASL_AUXPROP_PLUG_VERSION 4
  923.  
  924. /* default name for auxprop plug-in entry point is "sasl_auxprop_init"
  925.  *  similar to sasl_server_plug_init model, except only returns one
  926.  *  sasl_auxprop_plug_t structure;
  927.  */
  928. typedef int sasl_auxprop_init_t(const sasl_utils_t *utils,
  929.                 int max_version,
  930.                 int *out_version,
  931.                 sasl_auxprop_plug_t **plug,
  932.                 const char *plugname);
  933.  
  934. /* add an auxiliary property plug-in
  935.  */
  936. LIBSASL_API int sasl_auxprop_add_plugin(const char *plugname,
  937.                     sasl_auxprop_init_t *auxpropfunc);
  938.  
  939. typedef void auxprop_info_callback_t (sasl_auxprop_plug_t *m,
  940.                           sasl_info_callback_stage_t stage,
  941.                       void *rock);
  942.  
  943. /* Dump information about available auxprop plugins (separate functions are
  944.    used for canon and server authentication plugins) */
  945. LIBSASL_API int auxprop_plugin_info (const char *mech_list,
  946.     auxprop_info_callback_t *info_cb,
  947.     void *info_cb_rock);
  948.  
  949. #ifdef __cplusplus
  950. }
  951. #endif
  952.  
  953. #endif /* SASLPLUG_H */
  954.